Usage reader configuration

The Marketplace Managers or the developers can configure the usage reader to define the custom fields that can be mapped to the predetermined fields to create a customized event format and set up the rating logic for the selected products.

The Reader Configuration tab displays the following information in the Usage Readers section. The details are displayed only if any readers have been configured:

• Usage reader name
• Product name
• File format that was used
• Status
• Action ellipses which can be used to edit the reader configuration.

📝 Note: The edit option is not available if the usage reader is activated. For more information on the edit option, see Edit usage reader configuration.

Prerequisites

The product should have the Allow custom metered usage option enabled at the product level. For more information on enabling the option, see Add recurring editions.

To configure Usage reader perform the following steps:

1. Setup usage reader.
2. Map custom fields to the existing database fields.
3. Transform data to apply parsing logic for usage files.
4. Apply rating logic.
5. Review configuration

Setup Usage reader

The marketplace managers or the developers can set up the usage reader by uploading a sample file and selecting the fields to be mapped with the predetermined database fields. On uploading the sample file, all the fields in the file are identified and displayed in the Uploaded fields section.

To set up the usage reader:

1. Go to Manage > Marketplace > Dashboard | BILLING | Metered Usage.
   The Usage page opens.
2. Click the Reader Configuration tab.
3. Click Create.
   The Setup tab opens.
4. In the Setup tab, do the following:
   1. Reader Name - Provide the name for the custom usage reader.
   2. Product Tagging - Select the product for which the custom usage will be uploaded.
   3. Upload File - Upload the sample usage format file with the custom fields. The fields from this file are used to configure a new usage reader. To upload the file, Click Choose file and select the required file.
   4. Select ISV Fields - The fields from the uploaded file are displayed in the Uploaded fields section, click on the fields that you want to map. The selected fields are listed in the Selected fields section.
5. Click Next.
   The Field Mapping tab opens.

Map custom fields to predetermined database fields

You can map your custom data to the predetermined database fields, aggregate fields to generate the invoice line items, and define the usage line description that will appear on the generated invoice.

The aggregation logic defines how many usage lines for each account identifier the partner wants to see. If you select more aggregation fields then there will be a lesser number of lines in billing or downstream systems.

Example: If a usage file has 10K records for 10 subscriptions and usage file provides subscription identifier, product, and edition information in the file. Developers can decide to aggregate usage based on subscription identifier only, or subscription identifier + product, or subscription identifier + product + edition.

The usage line description goes to the partners for billing and order reports, they can integrate the description with their ERP systems to provide the invoice descriptions if required.

To map the custom fields, do the following in the Field Mapping tab:

1. From the ISV Field column, select the field you want to map to the fields in the Database Field column. The predetermined fields are:
   • accountId - map the field that contains the unique identifier to recognize the subscription for which the usage is provided. This field is mandatory.
   • Quantity - map the field that contains the number of units of usage in the stated unit of measure incurred by the user. This field is mandatory.
   • eventDate - map the field that contains the date and time when the usage event was recorded by the metering system. This field is mandatory.
   • eventId - map the field that contains the unique caller-provided identifier for each metered usage event.
   • currency - map the field that contains the currency in which the custom usage price (unitPrice) is reported.
   • pricingUnit - map the the field that contains the unit type for which the metered usage is being sent. If there is no mapping then the predefined product unit type will be used.
   • customUnit - map the the field that contains the unit of measure for reported custom usage. If there is no mapping then the predefined unit of measure will be used.
   • customUnitPrice - map the field that contains the custom price of the unit. If there is no mapping then the predefined unit price at the product level will be used provided the pricing unit matches, else this event will be ignored.
2. In the Aggregator field, from the drop-down, select the required fields for aggregation.To add more fields, click Add Field and select the required field.
3. In the Description section provide the following information to describe the usage line item:
   1. Prefix - Provide the prefix that will appear in the usage description. Example: company name or product name.
   2. Suffix - Provide the suffix that will appear in the usage description. Example: month or date the usage was processed.
   3. Separator - provide the separator that will be used to separate the prefix, suffix, and the ISV field you have chosen. Example: ‘,’.
   4. ISV field - select the field from the drop down that you want to display as the part of the usage description in the invoice.
4. The Description preview field shows the description line that will appear on the invoice based on the prefix, suffix, and ISV field you have selected.
5. Click Next.

The Data Transformation tab opens.

Transform data to apply parsing logic for the usage file

You can add the parsing logic for the usage file to transform the usage data as required.

To transform data, do the following in the Data Transformation tab:

1. In the Event date format field, provide the format in which the usage date is available in the usage file. The formats supported are:
   Supported date formats

   Date format	Example
   yyyy-MM-dd	2018-07-14
   dd-MMM-yyyy	14-Jul-2018
   dd/MM/yyyy	14/07/2018
   E, MMM dd yyyy	Sat, Jul 14 2018
   yyyy-MM-dd'T'HH:mm:ssZ	2018-07-14T14:31:30+0530

2. Click on Add transformer to add usage data transformers.

3. From the ISV field to transform drop down, select an ISV field to transform.

4. From the Transformer drop-down, select the data transformer you want to apply to the selected field. Additional fields like, Parameters and Arguments appear based on the transformer selected, enter the required values.
   The transformers available are:
   Supported date formats

   Transformer	Details
   Boolean	Transforms a string value to a boolean value. Example: "true" (string) will be converted to true(boolean)
   Decimal format	Formats a string representing a decimal/numeric value into a BigDecimal according to specified scale and precision. Example: In the Parameters, if you specify scale as 10 and precision as 30, then for "12345678901234567890.12345678901234567890", it will be rounded to 10 decimal places and checked against the configured precision of 30 digits and the result will be 1234567890.12345678901234567890.
   Constant Multiplier	Multiplies a BigDecimal value by a constant multiplier. Example: If the multiplier is 2.5 and value is 10, then it will multiply and give 25 as result.
   Rfc3339 Date Time	Converts the date-time strings in RFC3339 format into Instant objects. Example: "2024-03-19T12:30:00Z" When you pass this string to the RFC3339 DateTime transformer. The transformer converts this string into an Instant object which represents the same point in time.
   Local Date	Converts the timestamp in local date object in UTC time zone. Example: You have a timestamp representing a date: 1616198400000 (which corresponds to 2021-03-20T00:00:00Z). You pass this timestamp to the LocalDateTransformer. The transformer converts this timestamp into a LocalDate object in the UTC time zone. The resulting local date is 2021-03-20.
   Integer	Converts string representations of integers into Long objects. Example: If a string represents an integer value: "123". You pass this string to the IntegerTransformer. The transformer converts this string into a Long object representing the integer value 123.
   Is Present	Determines whether a specific field is present in a data object. Example: You have a data object with several fields, including name, age, and email. You want to check if the email field is present in the object. You pass the name of the field ("email") to the IsPresent transformer. The transformer checks if the email field is present in the data object. If the email field is present, it returns true. If the email field is not present, it returns false.
   Cost Type Datetime	Basic Usage: If the event is a regular service, like a consultation: Event Date: March 19, 2024 Cost Type: "Service Fee" The transformer simply converts the event date to an instant. Handling Billing Periods: If the event is related to a fee, such as a subscription renewal: Event Date: March 25, 2024 Cost Type: "Fee" Billing Start: March 20, 2024 Billing End: April 1, 2024 The transformer checks if the event date falls within the billing period. If it does, it returns the event date's instant. If not, it returns the last instant of the billing month (March 31, 2024 at 23:59:59.999).

5. Click Next.
   The Rating Logic tab opens.

Apply rating logic

You can use Rating logic to select the currency exchange rate to be applied to a usage event and to markup or markdown the rate for a usage event. To apply the markup or markdown, the usage event must have a field on which you can apply the rating logic.

To apply rating logic, do the following in the Rating Logic tab:

1. Select the currency exchange rate source from the Exchange rate source field drop-down. The options available are:
   1. Partner - The exchange rate is pre-defined by the partner, and is fetched using an API.
   2. Currency layer - The currency and the exchange rates are defined.
   3. Microsoft - Microsoft provides the exchange rate every month and if this option is selected then based on the event date the exchange rate is fetched from Microsoft exchange rate and applied to the usage event.
2. (Optional) Select Yes, in the Assign rate card option to mark up or mark down the rate for a usage event. Select No if you do not want any markup or markdown to be applied.
3. If you select Yes, then define the filter in the Query/Rule Builder section by defining the following information:
   1. In the Markup field, provide the markup or mark down percentage value. For markup provide a positive value, example: 10%. For markdown provide a negative value, example: -10%.
   2. In the ISV Field drop-down, select the field based on which the markup or markdown will be applied.
   3. In the Operator drop-down, select the operator to be applied on the select field.
   4. In the Value field, provide the value on which the markdown or markup will be applied.
      Example: You can mark up or mark down events that originate from a specific zip code by defining the rate card to markup 10% if the Zip Code = AAAA.
   5. To add more attributes, click Attributes and to delete an attribute click the “X” icon.
4. (Optional) To add more filters, click Filter and to delete a filter click the Trash icon.
   The Markup and rule preview field displays the description of the markup or markdown with the rules set.
5. Click Next.
   The Review Configuration tab opens.

Review configuration and activate usage reader

You can review all the configurations done from the Setup tab to the Rating Logic tab. If the configurations done are correct, then you can activate the usage reader.

To activate the usage reader

1. Click Save and activate reader to activate the usage reader.

Once the usage reader is saved and activated, the status of the usage reader in the Usage Readers list on the Reader Configuration tab turns green indicating that the usage reader is in active status. After the activation, the usage can be sent using the Json format in API or through the file upload option in the defined file format.